I suggest not to include algorithm for swap. As that header is quite big and may increase compilation overhead. How about creating one internally?

Why not using lowercase "swap" for the method name? In that case it could work hand in hand with std::swap() and std::swap(doc1, doc2) would automatically pick up the optimized implementation; otherwise std::swap() would do the unoptimized create-copy-temp-from-b, copy-a-to-b, copy-temp-to-a thing...

@miloyip Ok, I'll try to have a look.

@Kosta-Github Providing a lower-case swap member function would break the consistency of the RapidJSON API function naming conventions. Instead, we (or even users) could provide a lower-case swap in the rapidjson namespace, which should achieve the same thing.

Yeah, I am aware of the inconsistency but still think that easy/efficient interop with the STL is also worth to be considered.

Users most probably will not provide their own rapidjson::swap() function, because the usage of std::swap(doc1, doc2) already works out-of-the-box, but unfortunately with less-than-optimal performance.

@miloyip: I have now added a new helper function internal::Swap(), which avoids the dependency on the <algorithm> header.

@Kosta-Github: On my platform, std::swap doesn't work out of the box for GenericDocument/GenericValue as both classes are not copyable by default. If it works on your platform, then probably due to the enabled C++11 move support. In the latter case, the default swap is nearly as efficient than the explicit one.

We could add an "inline friend" function to GenericValue/GenericDocument to enable the common swap idiom:

    // add to GenericValue, GenericDocument (analogously)
    friend inline void swap(GenericValue& a, GenericValue& b) RAPIDJSON_NOEXCEPT
       { a.Swap(b); }

   // enables common pattern:
   using std::swap;
   swap(v1, v2); // calls GenericValue's friend through argument-dependent lookup

@miloyip, what do you think?

@pah I think both changes are OK for me.

I've just added the two free-standing friend swap functions.

Brilliant~